The following pages describe the commands available within the nShell(tm) environment. For the most part, these descriptions are copies of the "man pages" from the commands themselves. Man pages provide on-line help within the nShell system.
Each description contains the following information about a command:
NAME - is the command name
SYNOPSIS - is a grammatical description
DESCRIPTION - is an longhand verbal description
These may be followed by one or more of these optional headings:
OPTIONS - are the available options for the command
RETURN CODES - are special purpose return codes
SEE ALSO - refers the reader to other related topics
BUGS - is the list of currently known bugs
EXAMPLES - examples of command usage
OTHERS - is any other topics not included above
For more information see the entry for the "man" command.
For information about creating your own man pages, see the nShell Programmer's Guide.
.eq.
----
.eq. - Is parameter1 EQUAL TO parameter2?
SYNOPSIS
.eq. parameter1 parameter2
DESCRIPTION
If both parameters are legal integers, an integer comparison is performed. If either parameter is not an integer, a string comparison is performed.
These comparison commands may be used to test the return value from a previous command. It is important to note, however, that the comparison itself produces a return value and will overwrite "$?". For this reason, the return code should be saved into a temporary variable before a series of comparisons are performed:
command_x
set temp $? # save the result
if .lt. $temp 0 then echo "A serious error has occurred." endif
if .eq. $temp 0 then echo "Everything is ok" endif
if .gt. $temp 0 then echo "command_x returned a value of" $temp endif
RETURN CODES
<0 Error
0 True
1 False
SEE ALSO
.ge. .gt. .le. .lt. .ne.
.ge.
----
.ge. - Is parameter1 GREATER THAN OR EQUAL TO parameter2?
SYNOPSIS
.ge. parameter1 parameter2
DESCRIPTION
If both parameters are legal integers, an integer comparison is performed. If either parameter is not an integer, a string comparison is performed.
RETURN CODES
<0 Error
0 True
1 False
SEE ALSO
.eq. .gt. .le. .lt. .ne.
.gt.
----
.gt. - Is parameter1 GREATER THAN parameter2?
SYNOPSIS
.gt. parameter1 parameter2
DESCRIPTION
If both parameters are legal integers, an integer comparison is performed. If either parameter is not an integer, a string comparison is performed.
RETURN CODES
<0 Error
0 True
1 False
SEE ALSO
.eq. .ge. .le. .lt. .ne.
.le.
----
.le. - Is parameter1 LESS THAN OR EQUAL TO parameter2?
SYNOPSIS
.le. parameter1 parameter2
DESCRIPTION
If both parameters are legal integers, an integer comparison is performed. If either parameter is not an integer, a string comparison is performed.
RETURN CODES
<0 Error
0 True
1 False
SEE ALSO
.eq. .ge. .gt. .lt. .ne.
.lt.
----
.lt. - Is parameter1 LESS THAN parameter2?
SYNOPSIS
.lt. parameter1 parameter2
DESCRIPTION
If both parameters are legal integers, an integer comparison is performed. If either parameter is not an integer, a string comparison is performed.
RETURN CODES
<0 Error
0 True
1 False
SEE ALSO
.eq. .ge. .gt. .le. .ne.
.ne.
----
.ne. - Is parameter1 NOT EQUAL TO parameter2?
SYNOPSIS
.ne. parameter1 parameter2
DESCRIPTION
If both parameters are legal integers, an integer comparison is performed. If either parameter is not an integer, a string comparison is performed.
RETURN CODES
<0 Error
0 True
1 False
SEE ALSO
.eq. .ge. .gt. .le. .lt.
ask
---
ask - pop a three button modal dialog
SYNOPSIS
ask [-s | -m | -l] [strings...]
DESCRIPTION
The "ask" command displays a dialog and waits for the user to press one of three buttons.
The string parameters are concatenated within the dialog and are limited to a total of 255 characters. If no strings are given on the command line, standard input is used.
The three buttons are: "yes", "no" and "cancel".
OPTIONS
-s Display a small dialog
-m Display a medium dialog (default)
-l Display a large dialog
RETURN CODES
<0 Error
1 For "yes"
2 For "no"
3 For "cancel"
SEE ALSO
notify
BUGS
Strings may overrun the dialog size.
battery
-------
battery - display battery status
SYNOPSIS
battery
DESCRIPTION
This command uses the BatteryStatus system call. The current battery voltage and charger status are displayed.
Conditions which may be displayed are:
The charger is [dis]connected.
The charger has recently been [dis]connected.
The low voltage flag is set.
The high charging rate flag is set.
RETURN CODES
<0 Battery status could not be read.
0 Success
Note: Battery status information is only available on systems in which the Power Manager is installed.
beep
----
beep - make a beep sound
SYNOPSIS
beep
DESCRIPTION
This command calls the OSUtils SysBeep routine.
RETURN CODES
<0 Error
0 Success
cat
---
cat - copy to standard output
SYNOPSIS
cat [file1] [file2] . . .
DESCRIPTION
This command copies each of the specified files to standard output.
RETURN CODES
<0 Error
0 Success
cd
--
cd - change working directory
SYNOPSIS
cd "this:is:my new:path"
DESCRIPTION
The "cd" command allows the user to specify a new working directory. The working directory is held in the $PWD shell variable. If a partial pathname is given, a full path is generated using the existing $PWD variable. If no pathname is given, the user is returned to the $HOME directory.
Pathnames consist of volume and directory names separated by ':' characters. Pathnames may be "quoted", and must be when a volume or directory name contains a space.
SEE ALSO
pwd
chattr
------
chattr - change attributes
SYNOPSIS
chattr file [file2...] [-c crea] [-t type]
DESCRIPTION
A file's "type" and "creator" are used to track what kind of data is in a file, and what application the file belongs to.
The "chattr" command may be used to display or change these file attributes. When "chattr" is followed by one or more file names, a table of file creators and types will be displayed.
The -c and -t options may be used to change the file attributes.
OPTIONS
-c abcd Change file creator to 'abcd'
-t abcd Change file type to 'abcd'
RETURN CODES
<0 Error
0 Success
cp
--
cp - copy files
SYNOPSIS
cp source target
cp source [source2...] target
DESCRIPTION
The "cp" command copies files. This command may be used to copy one or more files to a target path. When one source file is specified, the destination may be a file or a directory. When more than one source file is specified, the target must be a directory.
RETURN CODES
<0 Error
0 Success
date
----
date - display system time
SYNOPSIS
date [-dmas]
DESCRIPTION
The "date" command uses the International Utilities Package to format a date and time string for display on standard output.
OPTIONS
-d Date only, the time is not printed.
-m Minutes only, seconds are not printed.
-a Abbreviated date format is used.
-s Short date format is used.
RETURN CODES
<0 Error
0 Success
SEE ALSO
try "man date examples"
delay
-----
delay - wait a specified amount of time
SYNOPSIS
delay [-m] delay_time
DESCRIPTION
The delay command will suspend shell operation for the specified length of time.
This command halts the current shell only. All other shells and applications will continue to run.
The delay_time is assumed to be specified in seconds, unless the -m option is used.
OPTIONS
-m The delay time is specified in minutes.
RETURN CODES
<0 Error
0 Success
echo
----
echo - repeat a string
SYNOPSIS
echo [string...]
DESCRIPTION
The "echo" command displays a string parameter on standard output. If more than one string parameter is given they are concatenated. The combined string may not exceed 255 characters.
RETURN CODES
<0 Error
0 Success
env
---
env - list shell variables
SYNOPSIS
env [name1] [name2] . . .
DESCRIPTION
The "env" command will list the current shell environment. Variables are listed with their values. If no parameters are given, all active shell variables are listed.
Variable names are limited to the characters a-z, A-Z, 0-9, _ and may be 31 characters in length.
RETURN CODES
<0 An error prevented the search
0 Successful search (inc. name not found)
SEE ALSO
set, unset
exit
----
exit - exit script
SYNOPSIS
exit [return code]
DESCRIPTION
The "exit" command causes an immediate return from a script. An integer return code may be set and later accessed using the $? pseudo variable. When no parameter is given, a code of 0 is returned.
When the "exit" command is used on the command line, it cancels all processing and sets the specified return code.
EXAMPLES
#
# test usage
#
if .ne. $# 2 then
echo "Usage: cmd filename"
exit -1
endif
export
------
export - export a shell variable from a script
SYNOPSIS
export variable_name
DESCRIPTION
The "export" command copies a shell variable from the current script environment to that of the parent. The "export" operation copies variables up a single level. To export variables from nested scripts, a series of "export" commands would be required.
The "export" command should only be used from within scripts, and fails when typed directly on the command line.
EXAMPLES
#
# set the working directory and export the corresponding variable
#
cd "my disk:my favorite tools:tools"
export PWD
gestalt
-------
gestalt - display system gestalt information
SYNOPSIS
gestalt [-d] OSType [OSType...]
DESCRIPTION
This command displays response codes from the system Gestalt call. This call is used to test the version or availability of system resources. As an example, the command "gestalt sysv" will display the version of your system software.
The OSType selectors must be specified as four character strings, as in sysv or "os ". Quotes are required when the selectors contain spaces.
The return codes are displayed as hexadecimal values, unless a -d option is specified.
OPTIONS
-d Display the response codes in decimal.
RETURN CODES
<0 Error
0 Success
hello
-----
hello - a minimal command
SYNOPSIS
hello
DESCRIPTION
The "hello" command is included as a minimal example of an nShell(tm) command. Source code for this command is discussed in the nShell Programmers' Guide.
RETURN CODES
<0 Error
0 Success
if
--
if - conditional execution
SYNOPSIS
if <commands1> then <commands2> [else <commands3>] endif
DESCRIPTION
If the result of the last command of the set <commands1> completes without error (result = zero), then the <commands2> clause will be executed.
If the result of the last command of the set <commands1> produces an error (result <> zero), and an else-clause is present, that clause will execute.
Flow of control statements are available in nShell-Pro(tm)
RETURN CODES
<0 Error
0 Success
SEE ALSO
while, until
EXAMPLES
if yesno "Should I say hello?" then hello endif
launch
------
launch - start an application
SYNOPSIS
launch application_path [document_path]
DESCRIPTION
This command will launch a specified application. If a document is specified, it will be opened when the application is launched.
This command requires System 7.
RETURN CODES
<0 Error
0 Success
ls
--
ls - list directory contents
SYNOPSIS
ls [[-c cols] | [-l [-g] [-b]]] [pathname]
DESCRIPTION
The "ls" command is included as a method of listing directory contents.
OPTIONS
-c list the directory contents in the specified number of columns.
-l long listing
-g specifies file creation dates on long listings
-b specifies file backup dates on long listings
RETURN CODES
<0 Error
0 Success
man
---
man - command line manual
SYNOPSIS
man command [section]
DESCRIPTION
The "man" program reads a descriptive text resource from within a selected command and writes that text to standard output.
Note: Man pages are available for flow-of-control statements, but they must be quoted so that the shell knows how to execute them:
man "if"
man "while"
RETURN CODES
<0 Error
0 Success
SEE ALSO
try "man man resources"
The nShell Programmer's Guide contains additional information on writing man resources.
mem
---
mem - show free memory
SYNOPSIS
mem
DESCRIPTION
The "mem" command prints the free space in the current heap zone on standard output.
RETURN CODES
<0 Error
0 Success
mkdir
-----
mkdir - create directories
SYNOPSIS
mkdir dir [dir2...]
DESCRIPTION
The "mkdir" command creates directories. Full or partial pathnames may be used to specify the new directories.
RETURN CODES
<0 Error
0 Success
mv
--
mv - move files
SYNOPSIS
mv source target
mv source [source2...] target
DESCRIPTION
The "mv" command moves files. This command may be used to move one or more files to a target path. When one source file is specified, the destination may be a file or a directory. When more than one source file is specified, the target must be a directory.
RETURN CODES
<0 Error
0 Success
notify
------
notify - pop an informational dialog
SYNOPSIS
notify [-s | -m | -l] [strings...]
DESCRIPTION
The "notify" command displays a dialog and waits for the user to press an acknowledgement button.
The string parameters are concatenated within the dialog and are limited to a total of 255 characters. If no strings are given on the command line, standard input is used.
RETURN CODES
<0 Error
0 Success
SEE ALSO
ask
BUGS
Strings may overrun the dialog size.
odoc
----
odoc - open a document
SYNOPSIS
odoc document_path [application_path]
DESCRIPTION
This command will open a specified document. If an application is specified, a message will be sent to that application to open the document. If no application is specified, the document's creator will be used.
This command requires System 7.
RETURN CODES
<0 Error
0 Success
path
----
path - define a command search path
SYNOPSIS
path "this:is:path:one/this:is:path:two"
DESCRIPTION
The "path" command allows the user to specify a command search path. The path is stored in the $PATH shell variable. Directories are separated by ":", and paths are separated by "/". A single ":" may be used to specify the current directory, as in "path :/this:is:path:two" .
Any variables used in the path are evaluated when you issue the path command. In the command "path $HOME:bin", the value of $HOME is evaluated immediately. If you change the value of $HOME later, the path will continue to point to the original :bin directory.
The default path is ":/$HOME:bin".
RETURN CODES
<0 Error
0 Success
SEE ALSO
which
pathchk
-------
pathchk - evaluates a full or partial pathname
SYNOPSIS
pathchk pathname
DESCRIPTION
The nShell environment uses traditional Macintosh pathnames. The "pathchk" command is included to allow the user to experiment with those pathnames.
Given a full or partial pathname, pathchk will echo the equivalent full pathname.
Pathchk does not check to see if any of the specified volumes, directories, or files exist.
RETURN CODES
<0 Error
0 Success
SEE ALSO
which
ps
--
ps - process status information
SYNOPSIS
ps
DESCRIPTION
The "ps" command lists information from the Process Manager. This information includes the I.D., the Creator and Type, and the memory usage for each process.
RETURN CODES
<0 Error
0 Success
pwd
---
pwd - print working directory
SYNOPSIS
pwd
DESCRIPTION
The "pwd" command prints the full path of the current working directory. The working directory is stored in the $PWD shell variable.
RETURN CODES
<0 Error
0 Success
SEE ALSO
cd
set
---
set - set environmental variables
SYNOPSIS
set name [value]
DESCRIPTION
The "set" command allows the operator to set variables within the shell environment. The normal syntax includes a "value" string. If no value is given, the shell variable is set equal to a null string.
Variable names are limited to the characters a-z, A-Z, 0-9, _ and may be 31 characters in length. The value string may contain any character and may be 255 characters in length.
RETURN CODES
<0 An error prevented the assignment
0 Successful assignment
SEE ALSO
unset, env
rm
--
rm - remove files
SYNOPSIS
rm file [file2...]
DESCRIPTION
The "rm" command will delete each file in a list. Missing files are skipped. If a directory is specified as a parameter to "rm", it is skipped as well.
RETURN CODES
<0 Error
0 Success
rmdir
-----
rmdir - remove directories
SYNOPSIS
rmdir dir [dir2...]
DESCRIPTION
The "rmdir" will delete each directory in a list. Missing directories are skipped. If a file is specified as a parameter to "rm", it is skipped as well. Directories must be empty to be deleted.
RETURN CODES
<0 Error
0 Success
unset
-----
unset - remove a shell variable
SYNOPSIS
unset name
DESCRIPTION
The "unset" command removes the named variable from the shell environment.
Variable names are limited to the characters a-z, A-Z, 0-9, _ and may be 31 characters in length.
RETURN CODES
<0 An error prevented the removal
0 Successful removal or name not found
SEE ALSO
set, env
until
-----
until - conditional execution
SYNOPSIS
until <commands1> do <commands2> done
DESCRIPTION
In this structure, the <commands1> clause will always execute. If the result of the last command of the set produces an error (result <> zero), then the <commands2> clause will be executed. Control will then return to the <commands1> clause, and the process will continue until the last command of this set completes without error (result = 0).
Flow of control statements are available in nShell-Pro(tm)
RETURN CODES
<0 Error
0 Success
SEE ALSO
while, if
EXAMPLES
until yesno "Should I STOP saying hello?" do hello done
which
-----
which - which copy of a command will be used
SYNOPSIS
which command
DESCRIPTION
"which" examines the command-search-path, and returns the location of the command which would be executed.
The which command first checks to see if the specified command is internal to the nShell application. Each directory in the search path is then examined to see if it contains an external command or shell script of the given name. Any 'TEXT' file with a matching name is assumed to be a shell script.
RETURN CODES
<0 Error or command not found
0 Success
SEE ALSO
path, pathchk
while
-----
while - conditional execution
SYNOPSIS
while <commands1> do <commands2> done
DESCRIPTION
In this structure, the <commands1> clause will always execute. If the result of the last command of the set completes without error (result = zero), then the <commands2> clause will be executed. Control will then return to the <commands1> clause, and the process will continue until the last command of this set produces an error (result <> 0).
Flow of control statements are available in nShell-Pro(tm)
RETURN CODES
<0 Error
0 Success
SEE ALSO
until, if
EXAMPLES
while yesno "Should I say hello?" do hello done
yesno
-----
yesno - ask a yes or no question
SYNOPSIS
yesno [-i] [string...]
DESCRIPTION
This command prompts the user for a “y” or “n” response. The string parameters are concatenated and may not exceed a total of 255 characters. If the -i option is used the prompt is read from standard input.
